<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>OnClipboardChange</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>OnClipboardChange</h1>

<p>A label named OnClipboardChange (if it exists) is launched automatically whenever any application (even the script itself) has changed the contents of the clipboard. The label also runs once when the script first starts.</p>
<p>The built-in variable A_EventInfo contains:<br>
  0 if the clipboard is now empty;<br>
1 if it contains something that can be expressed as text (this includes <a href="../misc/Clipboard.htm#CopiedFiles">files copied</a> from an Explorer window);<br>
2 if it contains something entirely non-text such as a picture.</p>
<p>The following example is a working script. Whenever it is running, it will briefly display a ToolTip for each clipboard change.</p>
<pre id="LabelExample">#Persistent
return

OnClipboardChange:
ToolTip Clipboard data type: %A_EventInfo%
Sleep 1000
ToolTip  <em>; Turn off the tip.</em>
return</pre>

&nbsp;
<h2 id="Function">OnClipboardChange() <span class="ver">[v1.1.20+]</span></h2>
<p>Registers a <a href="../Functions.htm">function</a> or <a href="../objects/Functor.htm">function object</a> to run whenever the clipboard's content changes.</p>

<pre class="Syntax">OnClipboardChange(Func [, AddRemove])</pre>
<h3>Parameters</h3>
<dl>

  <dt>Func</dt>
  <dd><p>A function name or <a href="../objects/Functor.htm">function object</a> to call. The function's parameter and return value are described <a href="#Func">below</a>.</p></dd>
  
  <dt>AddRemove</dt>
  <dd><p>One of the following values:<br>
  <strong>1</strong> (the default): Call the function after any previously registered functions.<br>
  <strong>-1</strong>: Call the function before any previously registered functions.<br>
  <strong>0</strong>: Do not call the function.</p>
  <p>If an OnClipboardChange label exists, it is always called first.</p></dd>

</dl>

<h3 id="Func">Func</h3>
<pre class="Syntax"><i>FunctionName</i>(Type)</pre>
<dl>
  <dt>Type</dt>
  <dd><p>Contains one of the following values:<br>
    <strong>0</strong> if the clipboard is now empty;<br>
    <strong>1</strong> if it contains something that can be expressed as text (this includes <a href="../misc/Clipboard.htm#CopiedFiles">files copied</a> from an Explorer window);<br>
    <strong>2</strong> if it contains something entirely non-text such as a picture.</p></dd>
  
  <dt><em>Return Value</em></dt>
  <dd><p>If this is the last or only OnClipboardChange function, the return value is ignored. Otherwise, the function can return a non-zero integer to prevent subsequent functions from being called.</p></dd>
</dl>

<h3 id="FunctionExample">Example</h3>
<p>This example is equivalent to <a href="#LabelExample">the one above</a>, except that the function is not called when the script first starts; only when the content of the Clipboard changes.</p>
<pre>#Persistent
OnClipboardChange("ClipChanged")
return

ClipChanged(Type) {
    ToolTip Clipboard data type: %Type%
    Sleep 1000
    ToolTip  <em>; Turn off the tip.</em>
}</pre>

<h2>Remarks</h2>
<p>If the clipboard changes while an OnClipboardChange label or function is already running, that notification event is lost. If this is undesirable,  specify <a href="../commands/Critical.htm">Critical</a> as the label's first line. However, this will also buffer/defer other <a href="../misc/Threads.htm">threads</a> (such as the press of a hotkey) that occur while the OnClipboardChange thread is running.</p>
<p>If the script itself changes the clipboard, its OnClipboardChange label or functions are typically not executed immediately; that is, commands immediately below the command that changed the clipboard are likely to execute beforehand. To force the label or functions to execute immediately, use a short delay such as <code><a href="../commands/Sleep.htm">Sleep 20</a></code> after changing the clipboard.</p>

<h3>Related</h3>
<p><a href="../misc/Clipboard.htm">Clipboard</a>, <a href="OnExit.htm">OnExit</a>, <a href="OnMessage.htm">OnMessage()</a>, <a href="RegisterCallback.htm">RegisterCallback()</a></p>

</body>
</html>
